/*
 * Copyright (C) 2008 Pleyo.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1.  Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 * 2.  Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 * 3.  Neither the name of Pleyo nor the names of
 *     its contributors may be used to endorse or promote products derived
 *     from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY PLEYO AND ITS CONTRIBUTORS "AS IS" AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL PLEYO OR ITS CONTRIBUTORS BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
#ifndef PlatformKeyboardEvent_h
#define PlatformKeyboardEvent_h
/**
 *  @file  PlatformKeyboardEvent.t
 *  PlatformKeyboardEvent description
 *  Repository informations :
 * - $URL$
 * - $Rev$
 * - $Date$
 */
#include "BALBase.h"

#include "PlatformString.h"
#include <wtf/Platform.h>






namespace WKAL {

    class PlatformKeyboardEvent : public WKALBase {
    public:
        enum Type {
            // KeyDown is sent by platforms such as Mac OS X, gtk and Qt, and has information about both physical pressed key, and its translation.
            // For DOM processing, it needs to be disambiguated as RawKeyDown or Char event.
            KeyDown,

            // KeyUp is sent by all platforms.
            KeyUp,

            // These events are sent by platforms such as Windows and wxWidgets. RawKeyDown only has information about a physical key, and Char
            // only has information about a character it was translated into.
            RawKeyDown,
            Char
        };

        enum ModifierKey {
            AltKey = 1 << 0,
            CtrlKey = 1 << 1,
            MetaKey = 1 << 2,
            ShiftKey = 1 << 3,
        };

    /**
     * get the keyboard event type ( KeyDown, KeyUp... )
     * @param[out] : keyboard event type
     * @code
     * Type t = key->type();
     * @endcode
     */
        Type type() const ;

    /**
     * disambiguate keyDown event if it's necessary
     * @param[in] : key event type
     * @param[in] : backward compatibility mode
     * @code
     * key->disambiguateKeyDownEvent(key->type()); or key->disambiguateKeyDownEvent(key->type(), true);
     * @endcode
     */
        void disambiguateKeyDownEvent(Type, bool backwardCompatibilityMode = false); // Only used on platforms that need it, i.e. those that generate KeyDown events.

     /**
     * Text as as generated by processing a virtual key code with a keyboard layout
     * (in most cases, just a character code, but the layout can emit several
     * characters in a single keypress event on some platforms).
     * This may bear no resemblance to the ultimately inserted text if an input method
     * processes the input.
     * Will be null for KeyUp and RawKeyDown events.
     * @param[out] : key event text 
     * @code
     * String keyText = key->text();
     * @endcode
     */
        String text() const ;

    /**
     * Text that would have been generated by the keyboard if no modifiers were pressed
     * (except for Shift); useful for shortcut (accelerator) key handling.
     * Otherwise, same as text().
     * @param[out] : unmodified text 
     * @code
     * String keyText = key->unmodifiedText();
     * @endcode
     */
        String unmodifiedText() const ;

    /**
     * Most compatible Windows virtual key code associated with the event.
     * Zero for Char events.
     * @param[out] : windows virtual keyCode
     * @code
     * int vk = key->windowsVirtualKeyCode();
     * @endcode
     */
        int windowsVirtualKeyCode() const ;
    /**
     * set the windows virtual keyCode
     * @param[in] : keyCode
     * @code
     * key->setWindowsVirtualKeyCode(0);
     * @endcode
     */
        void setWindowsVirtualKeyCode(int code) ;

    /**
     * return the key identifier
     * @param[out] : key identifier
     * @code
     * String id = key->keyIdentifier();
     * @endcode
     */
        String keyIdentifier() const ;

    /**
     * test if the auto repeat are activated
     * @param[out] : auto repeat value
     * @code
     * bool autoR = key->isAutoRepeat();
     * @endcode
     */
        bool isAutoRepeat() const ;

    /**
     * set auto repeat value
     * @param[in] : auto repeat value
     * @code
     * key->isAutoRepeat(false);
     * @endcode
     */
        void setIsAutoRepeat(bool in) ;

    /**
     * test if the key event value belongs to the keypad
     * @param[out] : true if the value belongs to the keypad, else false 
     * @code
     * bool keypad = key->isKeypad()
     * @endcode
     */
        bool isKeypad() const ;

    /**
     * test if the shift key are pressed
     * @param[out] : shift state ( true if pressed )
     * @code
     * bool keyshift = key->shiftKey()
     * @endcode
     */
        bool shiftKey() const ;

    /**
     * test if the ctrl key are pressed
     * @param[out] : ctrl state ( true if pressed )
     * @code
     * bool keyctrl = key->ctrlKey();
     * @endcode
     */
        bool ctrlKey() const ;

    /**
     * test if the alt key are pressed
     * @param[out] : alt state ( true if pressed )
     * @code
     * bool keyalt = key->altKey();
     * @endcode
     */
        bool altKey() const ;

    /**
     * test if the meta key are pressed
     * @param[out] : meta state ( true if pressed )
     * @code
     * bool keymeta = key->metaKey();
     * @endcode
     */
        bool metaKey() const ;

    /**
     * return all modifier values ( shift, alt, meta...)
     * @param[out] : modifier values
     * @code
     * unsigned mod = key->modifiers();
     * @endcode
     */
        unsigned modifiers() const ;

    /**
     * return the capslock state
     * @param[out] : capslock state
     * @code
     * bool cl = key->currentCapsLockState();
     * @endcode
     */
        static bool currentCapsLockState();



    /**
     * PlatformKeyboardEvent constructor
     * @param[in] : platform event
     * @code
     * PlatformKeyboardEvent ev = new PlatformKeyboardEvent(platformKeyEvent);
     * PlatformKeyEvent is a representation of the event on a specific platform ( for example SDL_KeyboardEvent on SDL )
     * @endcode
     */
        PlatformKeyboardEvent(BalEventKey*);

    /**
     * return the platform key event
     * @param[out] : platform event
     * @code
     * PlatformKeyEvent *ev = key->balEventKey();
     * PlatformKeyEvent is a representation of the event on a specific platform ( for example SDL_KeyboardEvent on SDL )
     * @endcode
     */
        BalEventKey* balEventKey() const;



    private:
        Type m_type;
        String m_text;
        String m_unmodifiedText;
        String m_keyIdentifier;
        bool m_autoRepeat;
        int m_windowsVirtualKeyCode;
        bool m_isKeypad;
        bool m_shiftKey;
        bool m_ctrlKey;
        bool m_altKey;
        bool m_metaKey;

        BalEventKey* m_balEventKey;
    };

} // namespace WKAL

#endif // PlatformKeyboardEvent_h




